.SP 30 
.SH
5 Running pLucid under UNIX
.SH
5.1 The Basics
.PP
This section of the manual explains how a pLucid
program runs in the UNIX environment.
.PP
The pLucid evaluator is itself a UNIX process and as such has
associated with it an input stream (the standard input), an
output stream (the standard output) and an output stream for
reporting of errors (the standard error). On most
implementations of UNIX the standard input is associated with the
user's keyboard and the standard output and standard error with the
user's
screen. It is possible in UNIX to redirect input and output to
places other than the screen and keyboard and
the reader is refered to the UNIX manual.
The following diagram shows how the pLucid evaluator interfaces
with the user:
.IB

  USER     STDIN      +------------------+  STDOUT
KEYBOARD ------------>| pLucid Evaluator |----------->
                      +------------------+               USER
                         |                  STDERROR     SCREEN
                         +--------------------------->
.IE
.PP
Many useful pLucid programs
never need use more than these three basic streams. The @filter
operator decribed in the next section explains how more input
and output streams may be associated with a pLucid program.
.PP
Let us begin with the most trivial of pLucid programs namely the
expression
.PR
        x
.PE
In this simple program there is no definition for @x, in other
words @x is a free variable of the expression.
In pLucid each free variable occuring in an expression is
associated with its own pLucid input stream and all pLucid
input streams take there input from the standard input (see
above).
Thus if we
run the above program the following prompt will a appear on
the screen
.IB
        x(0):
.IE
(Prompts for input and output are sent along the standard error
thus they can be discarded if they are of no help)
If we input a constant such as @@4.3&, @@[ 2 3 [ 4 ]]&, @@`a string'&,
or the word @@fred&; then our program will echo the input
e.g.
.IB
        x(0): 4.3
   output(0): 4.3
        x(1): [ 2 3 [ 4 ]]
   output(1): [ 2 3 [ 4 ]]
        x(2): `a string'
   output(2): `a string'
        ...     ...
        ...     ...
.IE
.PP
Note that when words are input, such as the input for x(2),
they must be input unquoted. Thus if we input @nil then we are
inputting the word @nil and not the empty list. To input
the empty list we use square bracket notation,
i.e. @@[]&.
.PP
Similarily, if we want to input the special object error
we shall use the symbol @@?&. e.g.
.IB
        x(3): ?
   output(3): ?
.IE
The special object eod is input as control-D. (or whatever the
local UNIX convention is for end of file) e.g.
.PH
        x(4): ^D
 % 
.PE
where % is the UNIX shell prompt. Thus the special object eod can be used
to gracefully terminate the evaluation of a continuously
operating program.
What is in effect happening is that the pLucid input stream
associated with @x is closed after an @eod has been read. All future
inputs on that particular pLucid stream are assumed to be @@eod&.
.SH
Pop input versus character input
.PP
In UNIX processes communicate to each other by sending streams
of characters. For example the date command
sents a stream of charaters on its standard output
to the user's screen. This stream of characters are those which
make up the current date and time.
In pLucid there are no objects of type character, so how does
pLucid manage to run in the UNIX environment ?
.PP
When a pLucid program is run, it normally expects all
of its inputs and outputs to be either numbers, words, strings or finite
lists, succussive inputs and outputs being separated by white space.
However there are options available that allow input or
output or both to take a different form.
.SH
Character input
.PP
In this mode the values read from the standard input are
assumed to be raw characters. As far as the pLucid program is
concerned a character is a string of length one. Note that these characters
may include control characters and non-printable characters.
These characters are represented in pLucid strings by  the
following escape sequences.
.DS
     @`\\\\b'      for backspace
     @`\\\\n'      for newline
     @`\\\\t'      for tab
     @`\\\\f'      for formfeed
     @`\\\\r'      for carriage return
     @`\\\\\\\\'      for \\\\
     @`\\\\''      for '
.DE
In addition an arbitrary byte-sized bit pattern can be
generated by writing
.DS
     @\\\\DDD
.DE
where  @DDD is one, two or three octal digits.
For example:
.DS
    @`\\\\014'     is formfeed
    @`\\\\33'      is the character escape
.DE
The option for running the evaluator in character input mode is
given in the UNIX manual entry (the -c option). Note that Pop
and character input cannot be mixed. Programs that use only
the basic input stream must be evaluated either in
Pop input mode or character input mode.
.SH
Character output
.PP
This mode is similar to the normal output mode except that
there is no white space to seperate successive outputs and
string constants are stripped of their quotes and escaped
characters such as @\\n and @\\33 are output as the characters
they denote. The option for running the evaluator in character
output mode is given in the UNIX manual entry (the -s option). Again
programs must be evaluated either in Pop output mode or in character
output mode.
.SH
A simple program
.PP
The following is an example of a pLucid program (or filter)
to compress the blanks
in a file:
.PR
   input  whenever not (input eq ` ' and next input eq ` ' )
.PE
reads from the standard input
character by character taking each character to be a string of
length one. Similarly the output must be in character form and
so the -s option must be used. If we type the
above program into a file called compressblanks. We can then
compile this program to get the pLucid intermediate code in the
file compressblanks.i. When we run the evaluator as follows:
.IB
        luval -c -s compressblanks.i < text
.IE
the result is that the file text will be printed on the
screen with all blanks compressed.
.SH
More than one free variable
.PP
In the following program
.PR
        x or y
.PE
there are two free variables,
@x and @y and thus the evaluator associates with each variable
it's own pLucid input stream. To evaluate the program
successive values for @x and @y must be obtained from the user.
The first value required is the first value for @x, this is
because the @or operator evaluates its argument left to right.
e.g
.IB
        x(0): true
        y(0): false
   output(0): true
        x(1): ...
.IE
If the object eod is input as a value for one of these
variables, say @x, the effect will be to close the input stream
for that variable. Nevertheless, this does not terminate the
program, as according to the algebra associated with pLucid
.IB
        eod or true = true
.IE
Thus if the evaluator receives eod as input for @x it will
close the stream associated with @x (i.e. all future input on @x
are @@eod&). However since the input stream for @y is still open and
since, given eod as it's
first argument, the @or operator need not terminate,
the evaluator will demand the next input for
@@y&.
If the input is @true the evaluator outputs @true and continues
evaluation. Note that values of @x will no longer be required
since the input stream for @x is closed. Thus only values of @y
are demanded and so long as these values are @true the
computation continues, any other value for @y will cause the
program to terminate.
.PP
A simpler example of a program with two free variables is
.PR
        x + y
.PE
When this program is run, it will ask for values for the
variables @x and @y.
If one of the input values for @x or @y is @eod
then the program terminates. This is
because in the algebra associated with pLucid,
.PH
        eod + z = eod  for any value z.
.PE
.SH
pLucid programs as standard UNIX processes
.PP
As pLucid programs run as standard UNIX processes
we can do all the usual things:
.PH
        luval lex.i < filename
.PE
if the file lex contains the program
.PR
 x
.PE
then this will read in constants
(i.e. @@[ 1 [2 3] 4]&, @@`a string'&, @@3.33&, @@~9&)
from file filename and output them to the terminal. Similarly
.PH
        luval lex.i > filename
.PE
will read constants one by one from the terminal and output
them to the file @@filename&. We can also combine these to read
constants from one file and output then to another. Our program
is then in effect a filter.
.IB
       luval lex.e < file1 > file2
.IE
.SH
5.2 The filter and arg operators
.PP
The @filter function enables pLucid programs to interact in a
simple manner with many useful UNIX utilities. The @filter function
takes the following form:
.IB
     filter(expression1,expression2,expression3)
.IE
The evaluation of a filter expression entails the following.
Firstly evaluate expression1, which should evaluate to a
string. This string is taken to be the name of a UNIX
process. The pLucid evaluator then spawns a UNIX process named
by this first argument. The second argument to the function
@filter is the stream of values that are to be sent
to the standard input of the
newly created process. Values produced by the newly created
process are passed along its standard output back into the
pLucid program and appear as the result of the function @filter.
The third
argument of filter should again be of type string. This
string is used to specify how the pLucid program
is to interact the process spawned by @@filter&.
The options for this are as follows:
.DS
    @`s'    Write to the stream associated with output to
           the filter in Character output mode.
    @`c'    Read the stream associated with input from the
           filter as a stream of raw charaters. That is use
           Character input to read the stream produced by the
           the process spawned by filter.
    @`i'    The filter requires no inputs.
    @`p'    For every input sent to the filter it
           will guarantee to return one value.
           i.e the filter is pointwise.
.DE
The third argument can be the empty string @`' which means that
input and output to this filter should be in pop mode. Note
that the above options can be combined in the same string
e.g. @@`csi'&.
The last two options have been included for reasons of
efficiency, it is beyond the scope of this manual to explain
why they are needed.
The following diagram illustrates what happens when a filter is
spawned by a pLucid program:
.IB
                             +------+
          Filter's STDIN  +->|FILTER|-+   Filter's STDOUT
                          |  +------+ |
                          |           |
           OUTPUT stream  |           |   INPUT stream to evaluator
          from evaluator  |           |
                          |           |
           STDIN          |           V     STDOUT
                      +-----------------+
         ------------>| pLucid Evaluator|------->
                      +-----------------+
                                |
                                |           STDERROR
                                +--------------->
.IE
Note that due to the UNIX limitations on the number of processes
and pipes that can be active at any one time, it is not
advisable to include a @filter function in a recusive function
definition where it can be called upon to spawn large numbers
of processes.

Note: the @filter function may also be used to interface
      programs written in other languages with a pLucid
      program. The only requirement is that the the process
      written in the other language acts as a filter with
      respect to its input/output behavoiur. This means that
      programs written in assembly language, Pascal,
      Fortran, PL/1 ... can be used in
      conjunction with a pLucid program.

.SH
An application of the filter function
.PP
In pLucid it is possible supply a program with input from a
file
via the standard input. For many applications this
method (i.e. luval prog.i < filename) is not
satisfactory because it forces the standard input to be the named
file. One way around this problem is to use the @filter
function which does not interfere with the evaluator's
standard input. The following function can be included in a
pLucid program. The function @file expects its argument to
evaluate to a string which it takes to be the name of a file.
The function then returns the stream of characters contained in
the named file terminated by the eod object.
.PH
   file(name) = filter( `cat <' ^ filename, `' , `ci')
                    where filename = first name; end;
.PE
This facility means that we can choose dynamically the name of the
files from which we require input.
.PP
.SH
5.3 Runtime errors
.PP
If a pLucid program compiles then the only errors that can
occur at runtime will be type clash errors or errors that occur from giving
a program strange inputs. A runtime type error will produce an
error message which will gives the exact location in the
original source (i.e file name , line number and cursor
postion of the error). If we run the following program:
.PR
moment where
        avg(x) = s / n
                where
                   s = x fby hd s + next x;
                   // We have included a deliberate mistake
                   // The above definition should be
                   // s = x fby s + next x;
                   n = 1 fby  n + 1;
                end;

        a = 7 fby 2 fby 4;

        moment = avg((a-m)*(a-m))
                  where
                    m is current m;
                  end;

        m = avg(a);
end
.PE
the evaluator will give use the following runtime error
messages:
.IB
Evaluation begins .........
 output(  0) : 0
---------------------------------------------------------------------------
Evaluation time error on line 4, of file bug
                    s = x fby hd s + next x;
 .............................^
arg of hd must be a list, not  7

Evaluation time error on line 4, of file bug
                    s = x fby hd s + next x;
 ..................................^
left arg of numeric binary operator
or condition of wvr or upon is ?

Evaluation time error on line 2, of file bug
         avg(x) = s / n
 ...................^

 ... and so on
.IE
Error messages like the above will appear on the screen if a
program containing type clashes is evaluated. Notice the
propagation of errors.
It is possible to
turn off error reporting (see the UNIX manual entry).

Note: if the source program is changed the program must be
recompiled otherwise the runtime error messages given by the
evaluator will be with reference to the source program used to
produce the current .i file.

.PP
If a program has a bug in it which is not a type error, that is
some form of logical error then the @filter function can be
used to probe variables in much the same way as an technician
uses
a scope and probe to debug a piece of faulty hardware.
The function @probe can be defined as follows:
.PH
  probe(name,expr) = filter(`tee '^filename,expr,`')
                      where filename = first name; end;
.PE
Note that in the above example the values of the suspect
variable have been tapped and stored in a file. On a system
that allowes a screen to be divided into multiple windows then
the values of the suspect variable could be displayed in one of
the windows.

.SH
The arg function
.PP
When invoking the evaluator it is often desirable to supply the
evaluator with the names of one or more files as arguments. For
example if we wanted to write the UNIX cat filter in pLucid we
would need to supply the name of the file that we wanted to
cat. To achieve this pLucid has the prefix operator @arg. The
@arg operator expects its argument to evaluate to a positive
integer which is used to select a string from the argument list
associated with the invocation of the evaluator. To invoke the
evaluator it is necessary to type the luval command which has
the following syntax:
.IB
   luval <option list> <filename>.i <argument list>
.IE
( See UNIX manual entry for more details). All that we need to
say here is that the @arg function will select a string from
the <argument list> of an evaluator invokation. If the argument
of @arg is not a positive integer or there is no argument with
that index then @arg yields the error object otherwise it
yields the appropriate string in the argument list.

.SH
 A facility for file inclusion
.PP
A simple file inclusion facility is provided.
To include a file (containing perhaps some function definitions)
in another, just say
.IB
       include "filename";
.IE
 NOTE that any other statement on the same line as the @include is
ignored.
.PP
Included files may also have @include statements, up to a level of
ten.
.PP
There is also a standard inclusion directory where many useful
functions are kept. In order to include files
from this directory in your program,
use angle brackets
instead of quotes, that is, say  

.IB
   include <filename>;
.IE
 where file name is a library file found in /ud/cscfac/faustini/lu/lib
(this directory name will probably be different on your
machine).
